@vamos-ui/react 0.0.0-stage → 0.2.0

package/dist/locale-data/tr/holidays.js

@@ -0,0 +1,81 @@
+/**
+ * Turkish public holidays (Law 2429 on national holidays and general holidays).
+ *
+ * Fixed-date holidays are generated for any year. Religious holidays follow the lunar calendar
+ * and are NOT computed: published dates can differ from computed Umm al-Qura dates. They ship
+ * as a static table from the Diyanet İşleri Başkanlığı "Dini Günler" calendar.
+ *
+ * Source: Diyanet İşleri Başkanlığı, Dini Günler takvimi 2025, 2026, 2027 (the 2027 table was
+ *         announced on 2026-08-24), cross-checked against national press listings of the
+ *         official holiday calendar.
+ * Verified: 2026-11-10. Review every year in January and extend `RELIGIOUS` (target 2035).
+ *
+ * Government "bridge" days (idari izin) bind only the public sector and are not included;
+ * add them as a custom provider (`createHolidayProvider`).
+ */
+import { addDays } from "../core/date.js";
+import { createHolidayProvider } from "../core/holidays.js";
+export const TR_HOLIDAYS_SOURCE = {
+    source: "Diyanet İşleri Başkanlığı — Dini Günler takvimi (2025–2027); Law 2429",
+    verifiedOn: "2026-11-10",
+    coverage: { from: "2025-01-01", to: "2027-12-31" },
+};
+/** First days of the religious holidays, as published by Diyanet. */
+export const TR_RELIGIOUS_HOLIDAYS = [
+    { year: 2025, ramazan: "2025-03-30", kurban: "2025-06-06", verified: true },
+    { year: 2026, ramazan: "2026-03-20", kurban: "2026-05-27", verified: true },
+    { year: 2027, ramazan: "2027-03-09", kurban: "2027-05-16", verified: true },
+];
+const FIXED = [
+    { md: "01-01", id: "tr-new-year", name: "New Year's Day", localName: "Yılbaşı" },
+    { md: "04-23", id: "tr-sovereignty-children", name: "National Sovereignty and Children's Day", localName: "Ulusal Egemenlik ve Çocuk Bayramı" },
+    { md: "05-01", id: "tr-labour", name: "Labour and Solidarity Day", localName: "Emek ve Dayanışma Günü" },
+    { md: "05-19", id: "tr-ataturk-youth-sports", name: "Commemoration of Atatürk, Youth and Sports Day", localName: "Atatürk'ü Anma, Gençlik ve Spor Bayramı" },
+    { md: "07-15", id: "tr-democracy", name: "Democracy and National Unity Day", localName: "Demokrasi ve Millî Birlik Günü" },
+    { md: "08-30", id: "tr-victory", name: "Victory Day", localName: "Zafer Bayramı" },
+    { md: "10-28", id: "tr-republic-eve", name: "Republic Day Eve", localName: "Cumhuriyet Bayramı Arifesi", partial: true },
+    { md: "10-29", id: "tr-republic", name: "Republic Day", localName: "Cumhuriyet Bayramı" },
+];
+const ORDINAL_EN = ["day 1", "day 2", "day 3", "day 4"];
+function religious(row) {
+    const out = [];
+    const feast = (first, days, key) => {
+        const en = key === "ramadan" ? "Ramadan Feast" : "Sacrifice Feast";
+        const tr = key === "ramadan" ? "Ramazan Bayramı" : "Kurban Bayramı";
+        out.push({ date: addDays(first, -1), id: `tr-${key}-eve`, name: `${en} Eve`, localName: `${tr} Arifesi`, kind: "public", partial: { from: "13:00" }, verified: row.verified });
+        for (let i = 0; i < days; i++) {
+            out.push({ date: addDays(first, i), id: `tr-${key}-${i + 1}`, name: `${en} (${ORDINAL_EN[i]})`, localName: `${tr} (${i + 1}. gün)`, kind: "public", verified: row.verified });
+        }
+    };
+    feast(row.ramazan, 3, "ramadan");
+    feast(row.kurban, 4, "sacrifice");
+    return out;
+}
+/** All Turkish public holidays of one year (religious ones only inside the table's coverage). */
+export function trHolidaysForYear(year) {
+    const y = String(year).padStart(4, "0");
+    const fixed = FIXED.map((f) => ({
+        date: `${y}-${f.md}`,
+        id: f.id,
+        name: f.name,
+        localName: f.localName,
+        kind: "public",
+        ...(f.partial ? { partial: { from: "13:00" } } : {}),
+        verified: true,
+    }));
+    const row = TR_RELIGIOUS_HOLIDAYS.find((r) => r.year === year);
+    return [...fixed, ...(row ? religious(row) : [])];
+}
+/**
+ * The `tr` holiday provider. Names are English in `name` and official Turkish in `localName`.
+ *
+ * ```ts
+ * trHolidays.get({ start: "2026-10-01", end: "2026-10-31" });
+ * // [{ date: "2026-10-28", name: "Republic Day Eve", partial: { from: "13:00" }, … }, { date: "2026-10-29", … }]
+ * ```
+ */
+export const trHolidays = createHolidayProvider({
+    id: "tr",
+    holidays: trHolidaysForYear,
+    coverage: { ...TR_HOLIDAYS_SOURCE.coverage },
+});

package/dist/locale-data/tr/iban.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Turkish IBAN: 26 characters = "TR" + 2 check digits + 5-digit bank code + reserved "0" +
+ * 16-character account number.
+ */
+import { formatIban } from "../core/iban.js";
+import type { IbanCountryRule, IdResult } from "../core/types.js";
+/**
+ * Bank names by 5-digit EFT participant code — the major banks only.
+ * TODO(data): replace with a table generated from the TCMB EFT participant list by script.
+ */
+export declare const TR_BANK_NAMES: Readonly<Record<string, string>>;
+/** The 5-digit bank code of a TR IBAN ("TR33 0006 1…" → "00061"). */
+export declare function trIbanBankCode(iban: string): string | undefined;
+export declare const trIbanRule: IbanCountryRule;
+/** Validates a Turkish IBAN (rejects other countries with `reason: "country"`). */
+export declare function validateTrIban(value: string): IdResult & {
+    bankCode?: string;
+    bankName?: string;
+};
+/** Display format "TR33 0006 1005 1978 6457 8413 26". */
+export declare const formatTrIban: typeof formatIban;

package/dist/locale-data/tr/iban.js

@@ -0,0 +1,45 @@
+/**
+ * Turkish IBAN: 26 characters = "TR" + 2 check digits + 5-digit bank code + reserved "0" +
+ * 16-character account number.
+ */
+import { formatIban, normalizeIban, validateIban } from "../core/iban.js";
+/**
+ * Bank names by 5-digit EFT participant code — the major banks only.
+ * TODO(data): replace with a table generated from the TCMB EFT participant list by script.
+ */
+export const TR_BANK_NAMES = {
+    "00010": "Ziraat Bankası",
+    "00012": "Halkbank",
+    "00015": "VakıfBank",
+    "00046": "Akbank",
+    "00062": "Garanti BBVA",
+    "00064": "İşbank",
+    "00067": "Yapı Kredi",
+    "00111": "QNB",
+    "00134": "DenizBank",
+    "00205": "Kuveyt Türk",
+};
+/** The 5-digit bank code of a TR IBAN ("TR33 0006 1…" → "00061"). */
+export function trIbanBankCode(iban) {
+    const v = normalizeIban(iban);
+    return v.startsWith("TR") && v.length >= 9 ? v.slice(4, 9) : undefined;
+}
+export const trIbanRule = {
+    country: "TR",
+    length: 26,
+    bban: /^\d{5}0[0-9A-Z]{16}$/,
+    bankName: (code) => TR_BANK_NAMES[code],
+};
+/** Validates a Turkish IBAN (rejects other countries with `reason: "country"`). */
+export function validateTrIban(value) {
+    const v = normalizeIban(value);
+    if (v && !v.startsWith("TR") && /^[A-Z]{2}/.test(v))
+        return { valid: false, value: v, reason: "country" };
+    const r = validateIban(v, [trIbanRule]);
+    if (!r.valid)
+        return r;
+    const bankCode = v.slice(4, 9);
+    return { ...r, bankCode, bankName: TR_BANK_NAMES[bankCode] };
+}
+/** Display format "TR33 0006 1005 1978 6457 8413 26". */
+export const formatTrIban = formatIban;

package/dist/locale-data/tr/id.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Turkish identification numbers: TCKN (citizens), YKN (foreign residents, same checksum,
+ * starts with 99) and VKN (tax number). Includes the combined tax-id rule used on invoices,
+ * where sole proprietors invoice with their TCKN (UBL-TR `PartyIdentification@schemeID`).
+ */
+import type { IdResult, IdRule } from "../core/types.js";
+/** The two TCKN check digits (d10, d11) for the first nine digits. */
+export declare function tcknCheckDigits(first9: string): string;
+/**
+ * Validates a TCKN or YKN.
+ *
+ * ```ts
+ * validateTckn("10000000146"); // { valid: true, value: "10000000146", kind: "tr-tckn" }
+ * validateTckn("99000000068"); // { valid: true, …, kind: "tr-ykn" }
+ * ```
+ */
+export declare function validateTckn(value: string): IdResult;
+/** The VKN check digit (d10) for the first nine digits. */
+export declare function vknCheckDigit(first9: string): string;
+/** Validates a 10-digit VKN (vergi kimlik numarası). */
+export declare function validateVkn(value: string): IdResult;
+/**
+ * Invoice tax id: a 10-digit VKN or an 11-digit TCKN / YKN. `kind` maps to the e-invoice
+ * scheme (`tr-vkn` → `VKN`, `tr-tckn` / `tr-ykn` → `TCKN`).
+ */
+export declare function validateTrTaxId(value: string): IdResult;
+/** UBL-TR `schemeID` for a valid tax id result. */
+export declare function trTaxSchemeId(result: IdResult): "VKN" | "TCKN" | undefined;
+/** Privacy mask for read-only views: first 3 and last 2 digits ("123******01"). */
+export declare function maskTrId(value: string, visibleStart?: number, visibleEnd?: number): string;
+/** TCKN / YKN rule for Formatted inputs. */
+export declare const trTcknRule: IdRule;
+/** VKN rule for Formatted inputs. */
+export declare const trVknRule: IdRule;
+/** Combined VKN-or-TCKN rule for invoice parties. */
+export declare const trTaxIdRule: IdRule;

package/dist/locale-data/tr/id.js

@@ -0,0 +1,120 @@
+const digitsOnly = (v) => v.replace(/[\s\-.]/g, "");
+/** The two TCKN check digits (d10, d11) for the first nine digits. */
+export function tcknCheckDigits(first9) {
+    const d = [...first9].map(Number);
+    if (d.length !== 9 || d.some((x) => !Number.isInteger(x)))
+        throw new RangeError("tcknCheckDigits: expected 9 digits");
+    const odd = d[0] + d[2] + d[4] + d[6] + d[8];
+    const even = d[1] + d[3] + d[5] + d[7];
+    const d10 = (((odd * 7 - even) % 10) + 10) % 10;
+    const d11 = (d.reduce((s, x) => s + x, 0) + d10) % 10;
+    return `${d10}${d11}`;
+}
+/**
+ * Validates a TCKN or YKN.
+ *
+ * ```ts
+ * validateTckn("10000000146"); // { valid: true, value: "10000000146", kind: "tr-tckn" }
+ * validateTckn("99000000068"); // { valid: true, …, kind: "tr-ykn" }
+ * ```
+ */
+export function validateTckn(value) {
+    const v = digitsOnly(value);
+    if (!v)
+        return { valid: false, value: v, reason: "empty" };
+    if (!/^\d+$/.test(v))
+        return { valid: false, value: v, reason: "chars" };
+    if (v.length !== 11)
+        return { valid: false, value: v, reason: "length" };
+    const kind = v.startsWith("99") ? "tr-ykn" : "tr-tckn";
+    if (v[0] === "0" || /^(\d)\1{10}$/.test(v))
+        return { valid: false, value: v, kind, reason: "pattern" };
+    if (tcknCheckDigits(v.slice(0, 9)) !== v.slice(9))
+        return { valid: false, value: v, kind, reason: "checksum" };
+    return { valid: true, value: v, kind };
+}
+/** The VKN check digit (d10) for the first nine digits. */
+export function vknCheckDigit(first9) {
+    const d = [...first9].map(Number);
+    if (d.length !== 9 || d.some((x) => !Number.isInteger(x)))
+        throw new RangeError("vknCheckDigit: expected 9 digits");
+    let sum = 0;
+    for (let i = 0; i < 9; i++) {
+        const t = (d[i] + 9 - i) % 10;
+        let r = (t * 2 ** (9 - i)) % 9;
+        if (t !== 0 && r === 0)
+            r = 9;
+        sum += r;
+    }
+    return String((10 - (sum % 10)) % 10);
+}
+/** Validates a 10-digit VKN (vergi kimlik numarası). */
+export function validateVkn(value) {
+    const v = digitsOnly(value);
+    if (!v)
+        return { valid: false, value: v, reason: "empty" };
+    if (!/^\d+$/.test(v))
+        return { valid: false, value: v, reason: "chars" };
+    if (v.length !== 10)
+        return { valid: false, value: v, reason: "length" };
+    if (vknCheckDigit(v.slice(0, 9)) !== v[9])
+        return { valid: false, value: v, kind: "tr-vkn", reason: "checksum" };
+    return { valid: true, value: v, kind: "tr-vkn" };
+}
+/**
+ * Invoice tax id: a 10-digit VKN or an 11-digit TCKN / YKN. `kind` maps to the e-invoice
+ * scheme (`tr-vkn` → `VKN`, `tr-tckn` / `tr-ykn` → `TCKN`).
+ */
+export function validateTrTaxId(value) {
+    const v = digitsOnly(value);
+    if (v.length === 11)
+        return validateTckn(v);
+    if (v.length === 10)
+        return validateVkn(v);
+    if (!v)
+        return { valid: false, value: v, reason: "empty" };
+    return { valid: false, value: v, reason: /^\d+$/.test(v) ? "length" : "chars" };
+}
+/** UBL-TR `schemeID` for a valid tax id result. */
+export function trTaxSchemeId(result) {
+    if (!result.valid)
+        return undefined;
+    return result.kind === "tr-vkn" ? "VKN" : "TCKN";
+}
+/** Privacy mask for read-only views: first 3 and last 2 digits ("123******01"). */
+export function maskTrId(value, visibleStart = 3, visibleEnd = 2) {
+    const v = digitsOnly(value);
+    if (v.length <= visibleStart + visibleEnd)
+        return v;
+    return v.slice(0, visibleStart) + "*".repeat(v.length - visibleStart - visibleEnd) + v.slice(-visibleEnd);
+}
+/** TCKN / YKN rule for Formatted inputs. */
+export const trTcknRule = {
+    id: "tr-tckn",
+    label: "Turkish ID number (TCKN)",
+    lengths: [11],
+    normalize: digitsOnly,
+    validate: validateTckn,
+    format: digitsOnly,
+    mask: (v) => maskTrId(v),
+};
+/** VKN rule for Formatted inputs. */
+export const trVknRule = {
+    id: "tr-vkn",
+    label: "Turkish tax number (VKN)",
+    lengths: [10],
+    normalize: digitsOnly,
+    validate: validateVkn,
+    format: digitsOnly,
+    mask: (v) => maskTrId(v, 3, 2),
+};
+/** Combined VKN-or-TCKN rule for invoice parties. */
+export const trTaxIdRule = {
+    id: "tr-tax-id",
+    label: "Tax number (VKN or TCKN)",
+    lengths: [10, 11],
+    normalize: digitsOnly,
+    validate: validateTrTaxId,
+    format: digitsOnly,
+    mask: (v) => maskTrId(v),
+};

package/dist/locale-data/tr/index.d.ts

@@ -0,0 +1,12 @@
+import type { LocaleDataPack, WeekInfo, WorkCalendar } from "../core/types.js";
+export { trHolidays, trHolidaysForYear, TR_HOLIDAYS_SOURCE, TR_RELIGIOUS_HOLIDAYS } from "./holidays.js";
+export { validateTckn, validateVkn, validateTrTaxId, tcknCheckDigits, vknCheckDigit, trTaxSchemeId, maskTrId, trTcknRule, trVknRule, trTaxIdRule } from "./id.js";
+export { validateTrIban, formatTrIban, trIbanBankCode, trIbanRule, TR_BANK_NAMES } from "./iban.js";
+export { trKdv, TR_KDV_RATES, activeTaxRates, vatFromNet, netFromGross, grossFromNet, withheldVat, allocateProRata, computeKdv, needsExemptionCode, trNumberToWords, trAmountInWords, type KdvLineInput, type KdvLineResult, type KdvBreakdown, type KdvOptions, } from "./kdv.js";
+export { loadTrAddressData, trProvinces, trDistricts, findTrProvince, checkTrPostalCode, trAddress, type TrAddressData, type TrAddressRow } from "./address.js";
+/** Monday start, Saturday–Sunday weekend, minimal days 1 (CLDR "TR"). */
+export declare const trWeekInfo: WeekInfo;
+/** A ready work calendar: Mon–Fri, 09:00–18:00, Turkish public holidays. */
+export declare const trWorkCalendar: WorkCalendar;
+/** The full `tr` pack. */
+export declare const trPack: LocaleDataPack;

package/dist/locale-data/tr/index.js

@@ -0,0 +1,33 @@
+// `tr` locale data pack: week info, holidays, ID / IBAN rules, KDV, address data. React-free.
+import { weekInfoForRegion } from "../core/week-info.js";
+import { trHolidays } from "./holidays.js";
+import { trTaxIdRule, trTcknRule, trVknRule } from "./id.js";
+import { trIbanRule } from "./iban.js";
+import { trAmountInWords, trKdv } from "./kdv.js";
+import { trAddress } from "./address.js";
+export { trHolidays, trHolidaysForYear, TR_HOLIDAYS_SOURCE, TR_RELIGIOUS_HOLIDAYS } from "./holidays.js";
+export { validateTckn, validateVkn, validateTrTaxId, tcknCheckDigits, vknCheckDigit, trTaxSchemeId, maskTrId, trTcknRule, trVknRule, trTaxIdRule } from "./id.js";
+export { validateTrIban, formatTrIban, trIbanBankCode, trIbanRule, TR_BANK_NAMES } from "./iban.js";
+export { trKdv, TR_KDV_RATES, activeTaxRates, vatFromNet, netFromGross, grossFromNet, withheldVat, allocateProRata, computeKdv, needsExemptionCode, trNumberToWords, trAmountInWords, } from "./kdv.js";
+export { loadTrAddressData, trProvinces, trDistricts, findTrProvince, checkTrPostalCode, trAddress } from "./address.js";
+/** Monday start, Saturday–Sunday weekend, minimal days 1 (CLDR "TR"). */
+export const trWeekInfo = weekInfoForRegion("TR");
+/** A ready work calendar: Mon–Fri, 09:00–18:00, Turkish public holidays. */
+export const trWorkCalendar = {
+    locale: "tr-TR",
+    workDays: [1, 2, 3, 4, 5],
+    businessHours: [{ start: "09:00", end: "18:00" }],
+    holidays: trHolidays,
+};
+/** The full `tr` pack. */
+export const trPack = {
+    code: "tr",
+    weekInfo: trWeekInfo,
+    holidays: trHolidays,
+    idRules: [trTcknRule, trVknRule, trTaxIdRule],
+    iban: [trIbanRule],
+    phone: { defaultCountry: "TR", displayFormat: "national" },
+    money: { currency: "TRY", suffixStyle: "local", amountInWords: trAmountInWords },
+    taxScheme: trKdv,
+    address: trAddress,
+};

package/dist/locale-data/tr/kdv.d.ts

@@ -0,0 +1,91 @@
+import type { IsoDate, TaxRate, TaxScheme } from "../core/types.js";
+/** Historic start dates are simplified to 2008-01-01: the kit only models rates from 2008 on. */
+export declare const TR_KDV_RATES: TaxRate[];
+/**
+ * KDV scheme. Exemption and withholding codes are a starter subset.
+ * TODO(data): generate the full lists from the GİB code lists and review them every January.
+ */
+export declare const trKdv: TaxScheme;
+/** Rates in force on `date`. */
+export declare function activeTaxRates(scheme: TaxScheme, date: IsoDate): TaxRate[];
+/** VAT on a net amount, half-up to 2 places ("100.00" at 20 → "20.00"). */
+export declare function vatFromNet(net: string, rate: number): string;
+/** Net from a VAT-inclusive amount: `gross / (1 + rate)`, half-up ("120.00" at 20 → "100.00"). */
+export declare function netFromGross(gross: string, rate: number): string;
+/** Gross from net: `net + vatFromNet(net)`. */
+export declare function grossFromNet(net: string, rate: number): string;
+/** Withheld VAT: `vat × num / den`, half-up ("18.00" at 9/10 → "16.20"). */
+export declare function withheldVat(vat: string, ratio: [number, number]): string;
+/**
+ * Splits `total` across `weights` pro-rata, exact to the kuruş (largest remainder), so the
+ * parts always add up to `total`. Used to allocate a document discount to line bases.
+ */
+export declare function allocateProRata(total: string, weights: string[]): string[];
+export interface KdvLineInput {
+    /** Decimal string; net or gross according to `entry`. Discounts already applied. */
+    amount: string;
+    /** Percent (20). */
+    rate: number;
+    entry?: "net" | "gross";
+    /** Withholding code from the scheme (e.g. "602"). */
+    withholding?: string;
+}
+export interface KdvLineResult {
+    net: string;
+    vat: string;
+    gross: string;
+    withheld: string;
+}
+export interface KdvBreakdown {
+    lines: KdvLineResult[];
+    /** "KDV Matrahı (%20)" / "Hesaplanan KDV (%20)" rows. */
+    byRate: {
+        rate: number;
+        base: string;
+        vat: string;
+    }[];
+    /** "KDV Tevkifatı (9/10)" rows. */
+    withholding: {
+        code: string;
+        ratio: [number, number];
+        vat: string;
+        withheld: string;
+    }[];
+    totalNet: string;
+    totalVat: string;
+    totalWithheld: string;
+    /** Net + VAT. */
+    grandTotal: string;
+    /** Grand total − withheld VAT. */
+    payable: string;
+}
+export interface KdvOptions {
+    scheme?: TaxScheme;
+    /** Default: the scheme's (`"line"` for tr-kdv). */
+    rounding?: "line" | "document";
+    /** A document-level discount on the net total, allocated pro-rata to line bases. */
+    documentDiscount?: string;
+}
+/**
+ * Per-line and per-rate KDV totals with exact half-up rounding. One implementation for client
+ * and server.
+ *
+ * ```ts
+ * computeKdv([{ amount: "1000.00", rate: 20, withholding: "602" }]);
+ * // totalVat "200.00", totalWithheld "180.00", grandTotal "1200.00", payable "1020.00"
+ * ```
+ */
+export declare function computeKdv(lines: KdvLineInput[], options?: KdvOptions): KdvBreakdown;
+/** True when a 0% line has the exemption code the scheme requires. */
+export declare function needsExemptionCode(scheme: TaxScheme, rate: number, code?: string): boolean;
+/** "1234" → "Bin İki Yüz Otuz Dört" (no "Bir" before "Bin" or "Yüz"). */
+export declare function trNumberToWords(n: bigint): string;
+/**
+ * Turkish amount in words for printed invoices.
+ *
+ * ```ts
+ * trAmountInWords("1234.50", "TRY"); // "Yalnız Bin İki Yüz Otuz Dört Türk Lirası Elli Kuruş"
+ * trAmountInWords("250", "USD");     // "Yalnız İki Yüz Elli ABD Doları"
+ * ```
+ */
+export declare function trAmountInWords(decimal: string, currency?: string): string;

package/dist/locale-data/tr/kdv.js

@@ -0,0 +1,222 @@
+/**
+ * Turkish VAT (KDV): rates, exemption and withholding (tevkifat) codes, and exact decimal
+ * helpers for net / gross / VAT, withholding, document discounts and per-rate breakdowns.
+ *
+ * Rates are dated data: 0 / 1 / 10 / 20 % since 10 July 2023 (Presidential Decree 7346; 8 → 10
+ * and 18 → 20). Calculations do not replace an accountant's review. The rounding mode must match
+ * the e-invoice integrator's or documents get rejected.
+ */
+import { fromUnits, mulDivRound, toUnits } from "../core/decimal.js";
+/** Historic start dates are simplified to 2008-01-01: the kit only models rates from 2008 on. */
+export const TR_KDV_RATES = [
+    { value: 0, label: "0%", validFrom: "2008-01-01" },
+    { value: 1, label: "1%", validFrom: "2008-01-01" },
+    { value: 8, label: "8%", validFrom: "2008-01-01", validTo: "2023-07-09" },
+    { value: 18, label: "18%", validFrom: "2008-01-01", validTo: "2023-07-09" },
+    { value: 10, label: "10%", validFrom: "2023-07-10" },
+    { value: 20, label: "20%", validFrom: "2023-07-10" },
+];
+/**
+ * KDV scheme. Exemption and withholding codes are a starter subset.
+ * TODO(data): generate the full lists from the GİB code lists and review them every January.
+ */
+export const trKdv = {
+    id: "tr-kdv",
+    rates: TR_KDV_RATES,
+    zeroRateRequiresExemption: true,
+    exemptionCodes: [
+        { code: "301", label: "Exports of goods (KDV Law 11/1-a)", localLabel: "11/1-a Mal ihracatı" },
+        { code: "350", label: "Other exemptions", localLabel: "Diğer istisnalar" },
+    ],
+    withholding: [
+        { code: "601", label: "Construction works and related engineering services", localLabel: "Yapım işleri ile bu işlerle birlikte ifa edilen mühendislik-mimarlık ve etüt-proje hizmetleri", ratio: [4, 10] },
+        { code: "602", label: "Survey, planning, consulting, audit and similar services", localLabel: "Etüt, plan-proje, danışmanlık, denetim ve benzeri hizmetler", ratio: [9, 10] },
+        { code: "604", label: "Catering services", localLabel: "Yemek servis hizmeti", ratio: [5, 10] },
+    ],
+    rounding: "line",
+    priceEntry: ["net", "gross"],
+};
+/** Rates in force on `date`. */
+export function activeTaxRates(scheme, date) {
+    return scheme.rates.filter((r) => r.validFrom <= date && (!r.validTo || r.validTo >= date));
+}
+const S = 2; // money scale
+const RS = 4; // rate scale
+const HUNDRED = 100n * 10n ** BigInt(RS);
+const rateUnits = (rate) => toUnits(String(rate), RS);
+/** VAT on a net amount, half-up to 2 places ("100.00" at 20 → "20.00"). */
+export function vatFromNet(net, rate) {
+    return fromUnits(mulDivRound(toUnits(net, S), rateUnits(rate), HUNDRED), S);
+}
+/** Net from a VAT-inclusive amount: `gross / (1 + rate)`, half-up ("120.00" at 20 → "100.00"). */
+export function netFromGross(gross, rate) {
+    return fromUnits(mulDivRound(toUnits(gross, S), HUNDRED, HUNDRED + rateUnits(rate)), S);
+}
+/** Gross from net: `net + vatFromNet(net)`. */
+export function grossFromNet(net, rate) {
+    const n = toUnits(net, S);
+    return fromUnits(n + mulDivRound(n, rateUnits(rate), HUNDRED), S);
+}
+/** Withheld VAT: `vat × num / den`, half-up ("18.00" at 9/10 → "16.20"). */
+export function withheldVat(vat, ratio) {
+    return fromUnits(mulDivRound(toUnits(vat, S), BigInt(ratio[0]), BigInt(ratio[1])), S);
+}
+/**
+ * Splits `total` across `weights` pro-rata, exact to the kuruş (largest remainder), so the
+ * parts always add up to `total`. Used to allocate a document discount to line bases.
+ */
+export function allocateProRata(total, weights) {
+    const t = toUnits(total, S);
+    const neg = t < 0n;
+    const abs = neg ? -t : t;
+    const w = weights.map((x) => {
+        const u = toUnits(x, S);
+        return u < 0n ? -u : u;
+    });
+    const sum = w.reduce((a, b) => a + b, 0n);
+    if (w.length === 0)
+        return [];
+    const parts = sum === 0n ? w.map((_, i) => (i === 0 ? abs : 0n)) : w.map((x) => (abs * x) / sum);
+    if (sum !== 0n) {
+        let left = abs - parts.reduce((a, b) => a + b, 0n);
+        const order = w.map((x, i) => ({ i, r: (abs * x) % sum })).sort((a, b) => (b.r > a.r ? 1 : b.r < a.r ? -1 : a.i - b.i));
+        for (let k = 0; left > 0n; k++, left--)
+            parts[order[k % order.length].i] += 1n;
+    }
+    return parts.map((p) => fromUnits(neg ? -p : p, S));
+}
+/**
+ * Per-line and per-rate KDV totals with exact half-up rounding. One implementation for client
+ * and server.
+ *
+ * ```ts
+ * computeKdv([{ amount: "1000.00", rate: 20, withholding: "602" }]);
+ * // totalVat "200.00", totalWithheld "180.00", grandTotal "1200.00", payable "1020.00"
+ * ```
+ */
+export function computeKdv(lines, options = {}) {
+    const scheme = options.scheme ?? trKdv;
+    const rounding = options.rounding ?? scheme.rounding;
+    const nets = lines.map((l) => (l.entry === "gross" ? netFromGross(l.amount, l.rate) : fromUnits(toUnits(l.amount, S), S)));
+    const discounts = options.documentDiscount ? allocateProRata(options.documentDiscount, nets) : nets.map(() => "0.00");
+    const ratioOf = (code) => (code ? scheme.withholding?.find((w) => w.code === code)?.ratio : undefined);
+    const out = lines.map((l, i) => {
+        const net = toUnits(nets[i], S) - toUnits(discounts[i], S);
+        // Gross entry without a document discount keeps the entered gross exactly.
+        const vat = l.entry === "gross" && !options.documentDiscount ? toUnits(l.amount, S) - net : mulDivRound(net, rateUnits(l.rate), HUNDRED);
+        const ratio = ratioOf(l.withholding);
+        const withheld = ratio ? mulDivRound(vat, BigInt(ratio[0]), BigInt(ratio[1])) : 0n;
+        return { net: fromUnits(net, S), vat: fromUnits(vat, S), gross: fromUnits(net + vat, S), withheld: fromUnits(withheld, S) };
+    });
+    const rateMap = new Map();
+    const whMap = new Map();
+    lines.forEach((l, i) => {
+        const r = rateMap.get(l.rate) ?? { base: 0n, vat: 0n };
+        r.base += toUnits(out[i].net, S);
+        r.vat += toUnits(out[i].vat, S);
+        rateMap.set(l.rate, r);
+    });
+    if (rounding === "document") {
+        for (const [rate, r] of rateMap)
+            r.vat = mulDivRound(r.base, rateUnits(rate), HUNDRED);
+    }
+    lines.forEach((l, i) => {
+        const ratio = ratioOf(l.withholding);
+        if (!ratio || !l.withholding)
+            return;
+        const w = whMap.get(l.withholding) ?? { ratio, vat: 0n, withheld: 0n };
+        w.vat += toUnits(out[i].vat, S);
+        w.withheld += toUnits(out[i].withheld, S);
+        whMap.set(l.withholding, w);
+    });
+    if (rounding === "document")
+        for (const w of whMap.values())
+            w.withheld = mulDivRound(w.vat, BigInt(w.ratio[0]), BigInt(w.ratio[1]));
+    const totalNet = [...rateMap.values()].reduce((s, r) => s + r.base, 0n);
+    const totalVat = [...rateMap.values()].reduce((s, r) => s + r.vat, 0n);
+    const totalWithheld = [...whMap.values()].reduce((s, w) => s + w.withheld, 0n);
+    return {
+        lines: out,
+        byRate: [...rateMap].sort((a, b) => b[0] - a[0]).map(([rate, r]) => ({ rate, base: fromUnits(r.base, S), vat: fromUnits(r.vat, S) })),
+        withholding: [...whMap].map(([code, w]) => ({ code, ratio: w.ratio, vat: fromUnits(w.vat, S), withheld: fromUnits(w.withheld, S) })),
+        totalNet: fromUnits(totalNet, S),
+        totalVat: fromUnits(totalVat, S),
+        totalWithheld: fromUnits(totalWithheld, S),
+        grandTotal: fromUnits(totalNet + totalVat, S),
+        payable: fromUnits(totalNet + totalVat - totalWithheld, S),
+    };
+}
+/** True when a 0% line has the exemption code the scheme requires. */
+export function needsExemptionCode(scheme, rate, code) {
+    return rate === 0 && !!scheme.zeroRateRequiresExemption && !scheme.exemptionCodes?.some((c) => c.code === code);
+}
+// ---------------------------------------------------------------------------------------------
+// Amount in words (required on printed Turkish invoices)
+// ---------------------------------------------------------------------------------------------
+const ONES = ["", "Bir", "İki", "Üç", "Dört", "Beş", "Altı", "Yedi", "Sekiz", "Dokuz"];
+const TENS = ["", "On", "Yirmi", "Otuz", "Kırk", "Elli", "Altmış", "Yetmiş", "Seksen", "Doksan"];
+const SCALES = ["", "Bin", "Milyon", "Milyar", "Trilyon", "Katrilyon"];
+function threeDigits(n) {
+    const h = Math.floor(n / 100);
+    const t = Math.floor((n % 100) / 10);
+    const o = n % 10;
+    const out = [];
+    if (h)
+        out.push(...(h > 1 ? [ONES[h]] : []), "Yüz");
+    if (t)
+        out.push(TENS[t]);
+    if (o)
+        out.push(ONES[o]);
+    return out;
+}
+/** "1234" → "Bin İki Yüz Otuz Dört" (no "Bir" before "Bin" or "Yüz"). */
+export function trNumberToWords(n) {
+    if (n === 0n)
+        return "Sıfır";
+    const neg = n < 0n;
+    let v = neg ? -n : n;
+    const groups = [];
+    while (v > 0n) {
+        groups.push(Number(v % 1000n));
+        v /= 1000n;
+    }
+    if (groups.length > SCALES.length)
+        throw new RangeError("trNumberToWords: number too large");
+    const words = [];
+    for (let i = groups.length - 1; i >= 0; i--) {
+        const g = groups[i];
+        if (!g)
+            continue;
+        if (i === 1 && g === 1)
+            words.push("Bin");
+        else
+            words.push(...threeDigits(g), ...(SCALES[i] ? [SCALES[i]] : []));
+    }
+    return (neg ? "Eksi " : "") + words.join(" ");
+}
+const CURRENCY_TR = {
+    TRY: ["Türk Lirası", "Kuruş"],
+    USD: ["ABD Doları", "Sent"],
+    EUR: ["Avro", "Sent"],
+    GBP: ["İngiliz Sterlini", "Peni"],
+    CHF: ["İsviçre Frangı", "Santim"],
+};
+/**
+ * Turkish amount in words for printed invoices.
+ *
+ * ```ts
+ * trAmountInWords("1234.50", "TRY"); // "Yalnız Bin İki Yüz Otuz Dört Türk Lirası Elli Kuruş"
+ * trAmountInWords("250", "USD");     // "Yalnız İki Yüz Elli ABD Doları"
+ * ```
+ */
+export function trAmountInWords(decimal, currency = "TRY") {
+    const units = toUnits(decimal, 2);
+    const abs = units < 0n ? -units : units;
+    const major = abs / 100n;
+    const minor = Number(abs % 100n);
+    const [majorName, minorName] = CURRENCY_TR[currency.toUpperCase()] ?? [currency.toUpperCase(), ""];
+    let out = `Yalnız ${units < 0n ? "Eksi " : ""}${trNumberToWords(major)} ${majorName}`;
+    if (minor)
+        out += ` ${trNumberToWords(BigInt(minor))}${minorName ? ` ${minorName}` : ""}`;
+    return out;
+}