@kashi-ui/persian 0.0.0-stage → 0.4.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Kashi contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,22 @@
-# Temporary Holding Version
+# @kashi-ui/persian
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+ابزارهای فارسی [کاشی](https://github.com/Sepantapouya/Kashi): تاریخ شمسی، ارقام فارسی، اعتبارسنجی کد ملی و شماره کارت. بدون وابستگی، برای مرورگر، Node.js و هر فریم‌ورکی.
+
+```bash
+npm i @kashi-ui/persian
+```
+
+```ts
+import { formatJalali, parseJalali, toISODate, isValidNationalId, getBankByCard, toEnDigits } from "@kashi-ui/persian";
+
+formatJalali(new Date(2024, 7, 2), { style: "full" }); // "جمعه ۱۲ مرداد ۱۴۰۳"
+parseJalali("۱۴۰۳/۵/۱۲");                            // Date
+toISODate(date);                                      // "2024-08-02" (بدون خطای منطقهٔ زمانی)
+isValidNationalId("۰۰۱۳۵۴۲۴۱۹");                      // true
+getBankByCard("610433")?.name;                        // "بانک ملت"
+toEnDigits("۰۹۱۲");                                   // "0912"
+```
+
+تبدیل تاریخ برای همهٔ روزهای سال‌های ۱۳۰۰ تا ۱۵۰۰ با تقویم persian کتابخانهٔ ICU تست شده است.
+
+مستندات کامل: [kashi.sepantapouya.com](https://kashi.sepantapouya.com/docs/persian/utilities/) · کد: [GitHub](https://github.com/Sepantapouya/Kashi) · لایسنس MIT

package/dist/card.d.ts

@@ -0,0 +1,12 @@
+export interface Bank {
+    /** نام فارسی */
+    name: string;
+    /** شناسهٔ لاتین برای کلاس یا لوگو */
+    slug: string;
+}
+/** اعتبارسنجی شماره کارت ۱۶ رقمی (الگوریتم Luhn) */
+export declare function isValidCardNumber(value: string): boolean;
+/** نام بانک از روی شش رقم اول؛ اگر شناخته نشود null */
+export declare function getBankByCard(value: string): Bank | null;
+/** گروه‌بندی چهارتایی: 6037991234567890 → 6037 9912 3456 7890 */
+export declare function formatCardNumber(value: string): string;

package/dist/card.js

@@ -0,0 +1,72 @@
+import { onlyDigits } from "./digits.js";
+// شش رقم اول کارت (BIN) بانک‌های ایرانی. فهرست ممکن است کامل نباشد؛ نام بانک فقط برای راهنمایی است.
+const BINS = {
+    "603799": { name: "بانک ملی", slug: "melli" },
+    "589210": { name: "بانک سپه", slug: "sepah" },
+    "627648": { name: "بانک توسعه صادرات", slug: "edbi" },
+    "627961": { name: "بانک صنعت و معدن", slug: "bim" },
+    "603770": { name: "بانک کشاورزی", slug: "keshavarzi" },
+    "639217": { name: "بانک کشاورزی", slug: "keshavarzi" },
+    "628023": { name: "بانک مسکن", slug: "maskan" },
+    "627760": { name: "پست بانک", slug: "postbank" },
+    "502908": { name: "بانک توسعه تعاون", slug: "tosee-taavon" },
+    "627412": { name: "بانک اقتصاد نوین", slug: "eghtesad-novin" },
+    "622106": { name: "بانک پارسیان", slug: "parsian" },
+    "639194": { name: "بانک پارسیان", slug: "parsian" },
+    "627884": { name: "بانک پارسیان", slug: "parsian" },
+    "502229": { name: "بانک پاسارگاد", slug: "pasargad" },
+    "639347": { name: "بانک پاسارگاد", slug: "pasargad" },
+    "627488": { name: "بانک کارآفرین", slug: "karafarin" },
+    "502910": { name: "بانک کارآفرین", slug: "karafarin" },
+    "621986": { name: "بانک سامان", slug: "saman" },
+    "639346": { name: "بانک سینا", slug: "sina" },
+    "639607": { name: "بانک سرمایه", slug: "sarmayeh" },
+    "636214": { name: "بانک آینده", slug: "ayandeh" },
+    "502806": { name: "بانک شهر", slug: "shahr" },
+    "504706": { name: "بانک شهر", slug: "shahr" },
+    "502938": { name: "بانک دی", slug: "dey" },
+    "603769": { name: "بانک صادرات", slug: "saderat" },
+    "610433": { name: "بانک ملت", slug: "mellat" },
+    "991975": { name: "بانک ملت", slug: "mellat" },
+    "627353": { name: "بانک تجارت", slug: "tejarat" },
+    "585983": { name: "بانک تجارت", slug: "tejarat" },
+    "589463": { name: "بانک رفاه", slug: "refah" },
+    "505785": { name: "بانک ایران زمین", slug: "iran-zamin" },
+    "606373": { name: "بانک قرض‌الحسنه مهر ایران", slug: "mehr-iran" },
+    "505416": { name: "بانک گردشگری", slug: "gardeshgari" },
+    "636795": { name: "بانک مرکزی", slug: "markazi" },
+    "585947": { name: "بانک خاورمیانه", slug: "khavarmianeh" },
+    "505809": { name: "بانک خاورمیانه", slug: "khavarmianeh" },
+    "507677": { name: "موسسه اعتباری نور", slug: "noor" },
+    "606256": { name: "موسسه اعتباری ملل", slug: "melal" },
+    "628157": { name: "موسسه اعتباری توسعه", slug: "tosee" },
+    "504172": { name: "بانک قرض‌الحسنه رسالت", slug: "resalat" },
+};
+/** الگوریتم Luhn */
+function luhn(digits) {
+    let sum = 0;
+    for (let i = 0; i < digits.length; i++) {
+        let d = Number(digits[digits.length - 1 - i]);
+        if (i % 2 === 1) {
+            d *= 2;
+            if (d > 9)
+                d -= 9;
+        }
+        sum += d;
+    }
+    return sum % 10 === 0;
+}
+/** اعتبارسنجی شماره کارت ۱۶ رقمی (الگوریتم Luhn) */
+export function isValidCardNumber(value) {
+    const n = onlyDigits(value);
+    return /^\d{16}$/.test(n) && luhn(n);
+}
+/** نام بانک از روی شش رقم اول؛ اگر شناخته نشود null */
+export function getBankByCard(value) {
+    const n = onlyDigits(value);
+    return n.length >= 6 ? (BINS[n.slice(0, 6)] ?? null) : null;
+}
+/** گروه‌بندی چهارتایی: 6037991234567890 → 6037 9912 3456 7890 */
+export function formatCardNumber(value) {
+    return onlyDigits(value).slice(0, 16).replace(/(\d{4})(?=\d)/g, "$1 ");
+}

package/dist/digits.d.ts

@@ -0,0 +1,12 @@
+/** ارقام لاتین را فارسی می‌کند: 1403 → ۱۴۰۳ */
+export declare function toFaDigits(value: string | number): string;
+/** ارقام فارسی و عربی را لاتین می‌کند: ۱۴۰۳ → 1403 */
+export declare function toEnDigits(value: string): string;
+/** فقط ارقام (با هر خطی) را نگه می‌دارد و لاتین برمی‌گرداند */
+export declare function onlyDigits(value: string): string;
+export interface FormatNumberOptions {
+    /** @default "fa" */
+    digits?: "fa" | "latin";
+}
+/** عدد با جداکنندهٔ هزارگان فارسی (٬): 1250000 → ۱٬۲۵۰٬۰۰۰ */
+export declare function formatNumber(value: number | string, { digits }?: FormatNumberOptions): string;

package/dist/digits.js

@@ -0,0 +1,25 @@
+const FA = "۰۱۲۳۴۵۶۷۸۹";
+const AR = "٠١٢٣٤٥٦٧٨٩";
+/** ارقام لاتین را فارسی می‌کند: 1403 → ۱۴۰۳ */
+export function toFaDigits(value) {
+    return String(value).replace(/\d/g, (d) => FA[Number(d)]);
+}
+/** ارقام فارسی و عربی را لاتین می‌کند: ۱۴۰۳ → 1403 */
+export function toEnDigits(value) {
+    return value.replace(/[۰-۹٠-٩]/g, (d) => {
+        const fa = FA.indexOf(d);
+        return String(fa >= 0 ? fa : AR.indexOf(d));
+    });
+}
+/** فقط ارقام (با هر خطی) را نگه می‌دارد و لاتین برمی‌گرداند */
+export function onlyDigits(value) {
+    return toEnDigits(value).replace(/\D/g, "");
+}
+/** عدد با جداکنندهٔ هزارگان فارسی (٬): 1250000 → ۱٬۲۵۰٬۰۰۰ */
+export function formatNumber(value, { digits = "fa" } = {}) {
+    const n = typeof value === "number" ? value : Number(onlyDigits(value));
+    if (!Number.isFinite(n))
+        return "";
+    const out = new Intl.NumberFormat("en-US").format(n);
+    return digits === "fa" ? toFaDigits(out).replace(/,/g, "٬") : out;
+}

package/dist/iban.d.ts

@@ -0,0 +1,9 @@
+import type { Bank } from "./card.js";
+/** ۲۴ رقم شبا بدون IR؛ «IR12 0170…» یا «۱۲۰۱۷۰…» را می‌پذیرد */
+export declare function ibanDigits(value: string): string;
+/** اعتبارسنجی شماره شبا (IBAN ایران): IR + ۲۴ رقم با رقم‌های کنترل ISO 13616 */
+export declare function isValidIban(value: string): boolean;
+/** نام بانک از روی شبا؛ اگر شناخته نشود null */
+export declare function getBankByIban(value: string): Bank | null;
+/** IR + گروه‌های چهارتایی: IR06 0170 0000 … */
+export declare function formatIban(value: string): string;

package/dist/iban.js

@@ -0,0 +1,62 @@
+import { toEnDigits } from "./digits.js";
+// کد سه‌رقمی بانک در شبا (رقم‌های ۵ تا ۷ پس از IR). فهرست ممکن است کامل نباشد.
+const BANK_CODES = {
+    "010": { name: "بانک مرکزی", slug: "markazi" },
+    "011": { name: "بانک صنعت و معدن", slug: "bim" },
+    "012": { name: "بانک ملت", slug: "mellat" },
+    "013": { name: "بانک رفاه", slug: "refah" },
+    "014": { name: "بانک مسکن", slug: "maskan" },
+    "015": { name: "بانک سپه", slug: "sepah" },
+    "016": { name: "بانک کشاورزی", slug: "keshavarzi" },
+    "017": { name: "بانک ملی", slug: "melli" },
+    "018": { name: "بانک تجارت", slug: "tejarat" },
+    "019": { name: "بانک صادرات", slug: "saderat" },
+    "020": { name: "بانک توسعه صادرات", slug: "edbi" },
+    "021": { name: "پست بانک", slug: "postbank" },
+    "022": { name: "بانک توسعه تعاون", slug: "tosee-taavon" },
+    "053": { name: "بانک کارآفرین", slug: "karafarin" },
+    "054": { name: "بانک پارسیان", slug: "parsian" },
+    "055": { name: "بانک اقتصاد نوین", slug: "eghtesad-novin" },
+    "056": { name: "بانک سامان", slug: "saman" },
+    "057": { name: "بانک پاسارگاد", slug: "pasargad" },
+    "058": { name: "بانک سرمایه", slug: "sarmayeh" },
+    "059": { name: "بانک سینا", slug: "sina" },
+    "060": { name: "بانک قرض‌الحسنه مهر ایران", slug: "mehr-iran" },
+    "061": { name: "بانک شهر", slug: "shahr" },
+    "062": { name: "بانک آینده", slug: "ayandeh" },
+    "064": { name: "بانک گردشگری", slug: "gardeshgari" },
+    "066": { name: "بانک دی", slug: "dey" },
+    "069": { name: "بانک ایران زمین", slug: "iran-zamin" },
+    "070": { name: "بانک قرض‌الحسنه رسالت", slug: "resalat" },
+    "078": { name: "بانک خاورمیانه", slug: "khavarmianeh" },
+};
+/** ۲۴ رقم شبا بدون IR؛ «IR12 0170…» یا «۱۲۰۱۷۰…» را می‌پذیرد */
+export function ibanDigits(value) {
+    return toEnDigits(value).toUpperCase().replace(/^\s*IR/, "").replace(/\D/g, "").slice(0, 24);
+}
+/** باقیماندهٔ تقسیم یک عدد بلند (به‌صورت رشته) بر ۹۷ */
+function mod97(numeric) {
+    let r = 0;
+    for (let i = 0; i < numeric.length; i += 7)
+        r = Number(String(r) + numeric.slice(i, i + 7)) % 97;
+    return r;
+}
+/** اعتبارسنجی شماره شبا (IBAN ایران): IR + ۲۴ رقم با رقم‌های کنترل ISO 13616 */
+export function isValidIban(value) {
+    const raw = toEnDigits(value).toUpperCase().replace(/[\s-]/g, "");
+    const digits = raw.startsWith("IR") ? raw.slice(2) : raw;
+    if (!/^\d{24}$/.test(digits))
+        return false;
+    // I=18، R=27؛ دو حرف و رقم‌های کنترل به انتهای شماره منتقل می‌شوند
+    return mod97(digits.slice(2) + "1827" + digits.slice(0, 2)) === 1;
+}
+/** نام بانک از روی شبا؛ اگر شناخته نشود null */
+export function getBankByIban(value) {
+    const d = ibanDigits(value);
+    return d.length >= 5 ? (BANK_CODES[d.slice(2, 5)] ?? null) : null;
+}
+/** IR + گروه‌های چهارتایی: IR06 0170 0000 … */
+export function formatIban(value) {
+    const d = ibanDigits(value);
+    return d ? `IR${d}`.replace(/(.{4})(?=.)/g, "$1 ") : "";
+}

package/dist/index.d.ts

@@ -0,0 +1,13 @@
+export { toFaDigits, toEnDigits, onlyDigits, formatNumber } from "./digits.js";
+export type { FormatNumberOptions } from "./digits.js";
+export { JALALI_MONTHS, WEEKDAYS, WEEKDAYS_SHORT, toJalali, toGregorian, isLeapJalaliYear, jalaliMonthLength, isValidJalaliDate, jalaliWeekday, formatJalali, parseJalali, toISODate, fromISODate, } from "./jalali.js";
+export type { JalaliDate, FormatJalaliOptions } from "./jalali.js";
+export { isValidNationalId } from "./national-id.js";
+export { isValidCardNumber, getBankByCard, formatCardNumber } from "./card.js";
+export type { Bank } from "./card.js";
+export { isValidIban, getBankByIban, formatIban, ibanDigits } from "./iban.js";
+export { normalizeMobile, isValidMobile, getMobileOperator, formatMobile } from "./mobile.js";
+export type { Operator } from "./mobile.js";
+export { numberToWords } from "./words.js";
+export { normalizePersian } from "./text.js";
+export type { NormalizeOptions } from "./text.js";

package/dist/index.js

@@ -0,0 +1,8 @@
+export { toFaDigits, toEnDigits, onlyDigits, formatNumber } from "./digits.js";
+export { JALALI_MONTHS, WEEKDAYS, WEEKDAYS_SHORT, toJalali, toGregorian, isLeapJalaliYear, jalaliMonthLength, isValidJalaliDate, jalaliWeekday, formatJalali, parseJalali, toISODate, fromISODate, } from "./jalali.js";
+export { isValidNationalId } from "./national-id.js";
+export { isValidCardNumber, getBankByCard, formatCardNumber } from "./card.js";
+export { isValidIban, getBankByIban, formatIban, ibanDigits } from "./iban.js";
+export { normalizeMobile, isValidMobile, getMobileOperator, formatMobile } from "./mobile.js";
+export { numberToWords } from "./words.js";
+export { normalizePersian } from "./text.js";

package/dist/jalali.d.ts

@@ -0,0 +1,40 @@
+export interface JalaliDate {
+    /** سال شمسی */
+    jy: number;
+    /** ماه ۱ تا ۱۲ */
+    jm: number;
+    /** روز ۱ تا ۳۱ */
+    jd: number;
+}
+export declare const JALALI_MONTHS: readonly ["فروردین", "اردیبهشت", "خرداد", "تیر", "مرداد", "شهریور", "مهر", "آبان", "آذر", "دی", "بهمن", "اسفند"];
+/** روزهای هفته از شنبه */
+export declare const WEEKDAYS: readonly ["شنبه", "یکشنبه", "دوشنبه", "سه‌شنبه", "چهارشنبه", "پنجشنبه", "جمعه"];
+export declare const WEEKDAYS_SHORT: readonly ["ش", "ی", "د", "س", "چ", "پ", "ج"];
+/** آیا سال شمسی کبیسه است؟ */
+export declare function isLeapJalaliYear(jy: number): boolean;
+/** تعداد روزهای یک ماه شمسی */
+export declare function jalaliMonthLength(jy: number, jm: number): number;
+/** آیا این تاریخ شمسی وجود دارد؟ */
+export declare function isValidJalaliDate(jy: number, jm: number, jd: number): boolean;
+/** تاریخ میلادی (Date، به وقت محلی) → شمسی */
+export declare function toJalali(date: Date): JalaliDate;
+/** شمسی → Date میلادی (نیمه‌شب به وقت محلی) */
+export declare function toGregorian(jy: number, jm: number, jd: number): Date;
+/** روز هفته با شروع از شنبه: ۰ = شنبه … ۶ = جمعه */
+export declare function jalaliWeekday(date: Date): number;
+export interface FormatJalaliOptions {
+    /** "numeric": ۱۴۰۳/۰۵/۱۲ — "long": ۱۲ مرداد ۱۴۰۳ — "full": جمعه ۱۲ مرداد ۱۴۰۳ @default "numeric" */
+    style?: "numeric" | "long" | "full";
+    /** @default "fa" */
+    digits?: "fa" | "latin";
+}
+export declare function formatJalali(date: Date, { style, digits }?: FormatJalaliOptions): string;
+/**
+ * تاریخ به شکل YYYY-MM-DD بر اساس وقت محلی، مناسب ارسال به سرور.
+ * از date.toISOString() استفاده نکنید: به UTC تبدیل می‌کند و در ایران (UTC+3:30) نیمه‌شب را روز قبل می‌کند.
+ */
+export declare function toISODate(date: Date): string;
+/** «2024-08-02» را به Date محلی (نیمه‌شب) تبدیل می‌کند؛ در صورت نامعتبر بودن null */
+export declare function fromISODate(text: string): Date | null;
+/** «۱۴۰۳/۵/۱۲»، «1403-05-12» یا «۱۴۰۳ ۰۵ ۱۲» را می‌خواند؛ در صورت نامعتبر بودن null */
+export declare function parseJalali(text: string): Date | null;

package/dist/jalali.js

@@ -0,0 +1,142 @@
+import { toEnDigits, toFaDigits } from "./digits.js";
+export const JALALI_MONTHS = [
+    "فروردین", "اردیبهشت", "خرداد", "تیر", "مرداد", "شهریور",
+    "مهر", "آبان", "آذر", "دی", "بهمن", "اسفند",
+];
+/** روزهای هفته از شنبه */
+export const WEEKDAYS = ["شنبه", "یکشنبه", "دوشنبه", "سه‌شنبه", "چهارشنبه", "پنجشنبه", "جمعه"];
+export const WEEKDAYS_SHORT = ["ش", "ی", "د", "س", "چ", "پ", "ج"];
+const BREAKS = [-61, 9, 38, 199, 426, 686, 756, 818, 1111, 1181, 1210, 1635, 2060, 2097, 2192, 2262, 2324, 2394, 2456, 3178];
+const div = (a, b) => ~~(a / b);
+const mod = (a, b) => a - ~~(a / b) * b;
+function jalCal(jy) {
+    const gy = jy + 621;
+    let leapJ = -14;
+    let jp = BREAKS[0];
+    let jump = 0;
+    if (jy < jp || jy >= BREAKS[BREAKS.length - 1])
+        throw new RangeError(`سال شمسی خارج از محدوده: ${jy}`);
+    for (let i = 1; i < BREAKS.length; i++) {
+        const jm = BREAKS[i];
+        jump = jm - jp;
+        if (jy < jm)
+            break;
+        leapJ += div(jump, 33) * 8 + div(mod(jump, 33), 4);
+        jp = jm;
+    }
+    let n = jy - jp;
+    leapJ += div(n, 33) * 8 + div(mod(n, 33) + 3, 4);
+    if (mod(jump, 33) === 4 && jump - n === 4)
+        leapJ += 1;
+    const leapG = div(gy, 4) - div((div(gy, 100) + 1) * 3, 4) - 150;
+    const march = 20 + leapJ - leapG;
+    if (jump - n < 6)
+        n = n - jump + div(jump + 4, 33) * 33;
+    let leap = mod(mod(n + 1, 33) - 1, 4);
+    if (leap === -1)
+        leap = 4;
+    return { leap, gy, march };
+}
+function g2d(gy, gm, gd) {
+    let d = div((gy + div(gm - 8, 6) + 100100) * 1461, 4) + div(153 * mod(gm + 9, 12) + 2, 5) + gd - 34840408;
+    d = d - div(div(gy + 100100 + div(gm - 8, 6), 100) * 3, 4) + 752;
+    return d;
+}
+function d2g(jdn) {
+    let j = 4 * jdn + 139361631;
+    j = j + div(div(4 * jdn + 183187720, 146097) * 3, 4) * 4 - 3908;
+    const i = div(mod(j, 1461), 4) * 5 + 308;
+    const gd = div(mod(i, 153), 5) + 1;
+    const gm = mod(div(i, 153), 12) + 1;
+    const gy = div(j, 1461) - 100100 + div(8 - gm, 6);
+    return { gy, gm, gd };
+}
+function j2d(jy, jm, jd) {
+    const r = jalCal(jy);
+    return g2d(r.gy, 3, r.march) + (jm - 1) * 31 - div(jm, 7) * (jm - 7) + jd - 1;
+}
+function d2j(jdn) {
+    const { gy } = d2g(jdn);
+    let jy = gy - 621;
+    const r = jalCal(jy);
+    let k = jdn - g2d(gy, 3, r.march);
+    if (k >= 0) {
+        if (k <= 185)
+            return { jy, jm: 1 + div(k, 31), jd: mod(k, 31) + 1 };
+        k -= 186;
+    }
+    else {
+        jy -= 1;
+        k += 179;
+        if (r.leap === 1)
+            k += 1;
+    }
+    return { jy, jm: 7 + div(k, 30), jd: mod(k, 30) + 1 };
+}
+/** آیا سال شمسی کبیسه است؟ */
+export function isLeapJalaliYear(jy) {
+    return jalCal(jy).leap === 0;
+}
+/** تعداد روزهای یک ماه شمسی */
+export function jalaliMonthLength(jy, jm) {
+    if (jm <= 6)
+        return 31;
+    if (jm <= 11)
+        return 30;
+    return isLeapJalaliYear(jy) ? 30 : 29;
+}
+/** آیا این تاریخ شمسی وجود دارد؟ */
+export function isValidJalaliDate(jy, jm, jd) {
+    return (Number.isInteger(jy) && Number.isInteger(jm) && Number.isInteger(jd) &&
+        jy >= -61 && jy <= 3177 && jm >= 1 && jm <= 12 && jd >= 1 && jd <= jalaliMonthLength(jy, jm));
+}
+/** تاریخ میلادی (Date، به وقت محلی) → شمسی */
+export function toJalali(date) {
+    return d2j(g2d(date.getFullYear(), date.getMonth() + 1, date.getDate()));
+}
+/** شمسی → Date میلادی (نیمه‌شب به وقت محلی) */
+export function toGregorian(jy, jm, jd) {
+    const { gy, gm, gd } = d2g(j2d(jy, jm, jd));
+    return new Date(gy, gm - 1, gd);
+}
+/** روز هفته با شروع از شنبه: ۰ = شنبه … ۶ = جمعه */
+export function jalaliWeekday(date) {
+    return (date.getDay() + 1) % 7;
+}
+export function formatJalali(date, { style = "numeric", digits = "fa" } = {}) {
+    const { jy, jm, jd } = toJalali(date);
+    const pad = (n) => String(n).padStart(2, "0");
+    let out;
+    if (style === "numeric")
+        out = `${jy}/${pad(jm)}/${pad(jd)}`;
+    else {
+        out = `${jd} ${JALALI_MONTHS[jm - 1]} ${jy}`;
+        if (style === "full")
+            out = `${WEEKDAYS[jalaliWeekday(date)]} ${out}`;
+    }
+    return digits === "fa" ? toFaDigits(out) : out;
+}
+/**
+ * تاریخ به شکل YYYY-MM-DD بر اساس وقت محلی، مناسب ارسال به سرور.
+ * از date.toISOString() استفاده نکنید: به UTC تبدیل می‌کند و در ایران (UTC+3:30) نیمه‌شب را روز قبل می‌کند.
+ */
+export function toISODate(date) {
+    const pad = (n) => String(n).padStart(2, "0");
+    return `${date.getFullYear()}-${pad(date.getMonth() + 1)}-${pad(date.getDate())}`;
+}
+/** «2024-08-02» را به Date محلی (نیمه‌شب) تبدیل می‌کند؛ در صورت نامعتبر بودن null */
+export function fromISODate(text) {
+    const m = text.match(/^(\d{4})-(\d{2})-(\d{2})$/);
+    if (!m)
+        return null;
+    const d = new Date(Number(m[1]), Number(m[2]) - 1, Number(m[3]));
+    return d.getMonth() === Number(m[2]) - 1 ? d : null;
+}
+/** «۱۴۰۳/۵/۱۲»، «1403-05-12» یا «۱۴۰۳ ۰۵ ۱۲» را می‌خواند؛ در صورت نامعتبر بودن null */
+export function parseJalali(text) {
+    const m = toEnDigits(text.trim()).match(/^(\d{4})\s*[/\-.\s]\s*(\d{1,2})\s*[/\-.\s]\s*(\d{1,2})$/);
+    if (!m)
+        return null;
+    const [jy, jm, jd] = [Number(m[1]), Number(m[2]), Number(m[3])];
+    return isValidJalaliDate(jy, jm, jd) ? toGregorian(jy, jm, jd) : null;
+}

package/dist/mobile.d.ts

@@ -0,0 +1,15 @@
+export interface Operator {
+    name: string;
+    slug: "mci" | "irancell" | "rightel";
+}
+/**
+ * شماره موبایل را به شکل استاندارد ۰۹xxxxxxxxx درمی‌آورد.
+ * +98912…، 0098912…، 98912… و 912… پذیرفته می‌شوند. اگر ساختار درست نباشد، ارقام همان‌طور برمی‌گردند.
+ */
+export declare function normalizeMobile(value: string): string;
+/** شماره موبایل ایران: ۱۱ رقم که با ۰۹ شروع می‌شود */
+export declare function isValidMobile(value: string): boolean;
+/** اپراتور از روی پیش‌شماره؛ اگر شناخته نشود null */
+export declare function getMobileOperator(value: string): Operator | null;
+/** ۰۹۱۲ ۳۴۵ ۶۷۸۹ */
+export declare function formatMobile(value: string): string;

package/dist/mobile.js

@@ -0,0 +1,38 @@
+import { onlyDigits } from "./digits.js";
+const MCI = { name: "همراه اول", slug: "mci" };
+const IRANCELL = { name: "ایرانسل", slug: "irancell" };
+const RIGHTEL = { name: "رایتل", slug: "rightel" };
+// پیش‌شماره‌ها پس از ۰۹؛ فهرست اپراتورهای اصلی، ممکن است کامل نباشد
+const PREFIXES = {
+    ...Object.fromEntries(["10", "11", "12", "13", "14", "15", "16", "17", "18", "19", "90", "91", "92", "93", "94"].map((p) => [p, MCI])),
+    ...Object.fromEntries(["01", "02", "03", "04", "05", "30", "33", "35", "36", "37", "38", "39", "41"].map((p) => [p, IRANCELL])),
+    ...Object.fromEntries(["20", "21", "22"].map((p) => [p, RIGHTEL])),
+};
+/**
+ * شماره موبایل را به شکل استاندارد ۰۹xxxxxxxxx درمی‌آورد.
+ * +98912…، 0098912…، 98912… و 912… پذیرفته می‌شوند. اگر ساختار درست نباشد، ارقام همان‌طور برمی‌گردند.
+ */
+export function normalizeMobile(value) {
+    let d = onlyDigits(value);
+    if (d.startsWith("0098"))
+        d = "0" + d.slice(4);
+    else if (d.startsWith("98") && d.length === 12)
+        d = "0" + d.slice(2);
+    else if (d.startsWith("9") && d.length === 10)
+        d = "0" + d;
+    return d;
+}
+/** شماره موبایل ایران: ۱۱ رقم که با ۰۹ شروع می‌شود */
+export function isValidMobile(value) {
+    return /^09\d{9}$/.test(normalizeMobile(value));
+}
+/** اپراتور از روی پیش‌شماره؛ اگر شناخته نشود null */
+export function getMobileOperator(value) {
+    const d = normalizeMobile(value);
+    return d.length >= 4 && d.startsWith("09") ? (PREFIXES[d.slice(2, 4)] ?? null) : null;
+}
+/** ۰۹۱۲ ۳۴۵ ۶۷۸۹ */
+export function formatMobile(value) {
+    const d = normalizeMobile(value).slice(0, 11);
+    return [d.slice(0, 4), d.slice(4, 7), d.slice(7, 11)].filter(Boolean).join(" ");
+}

package/dist/national-id.d.ts

@@ -0,0 +1,5 @@
+/**
+ * اعتبارسنجی کد ملی ایران (۱۰ رقم با رقم کنترل).
+ * ارقام فارسی و عربی و فاصله/خط تیره پذیرفته می‌شوند.
+ */
+export declare function isValidNationalId(value: string): boolean;

package/dist/national-id.js

@@ -0,0 +1,19 @@
+import { onlyDigits } from "./digits.js";
+/**
+ * اعتبارسنجی کد ملی ایران (۱۰ رقم با رقم کنترل).
+ * ارقام فارسی و عربی و فاصله/خط تیره پذیرفته می‌شوند.
+ */
+export function isValidNationalId(value) {
+    const id = onlyDigits(value);
+    if (!/^\d{10}$/.test(id))
+        return false;
+    // کدهای با ارقام تکراری (مثل ۱۱۱۱۱۱۱۱۱۱) رقم کنترل درست دارند ولی صادر نمی‌شوند
+    if (/^(\d)\1{9}$/.test(id))
+        return false;
+    const check = Number(id[9]);
+    let sum = 0;
+    for (let i = 0; i < 9; i++)
+        sum += Number(id[i]) * (10 - i);
+    const r = sum % 11;
+    return r < 2 ? check === r : check === 11 - r;
+}

package/dist/text.d.ts

@@ -0,0 +1,10 @@
+export interface NormalizeOptions {
+    /** خط ارقام خروجی؛ undefined یعنی بدون تغییر */
+    digits?: "fa" | "latin";
+}
+/**
+ * یکدست‌سازی متن فارسی برای ذخیره و جستجو:
+ * «ي» و «ى» عربی ← «ی»، «ك» ← «ک»، «ة» ← «ه»، حذف اعراب و کشیده (ـ)،
+ * و جمع کردن فاصله‌ها و نیم‌فاصله‌های تکراری.
+ */
+export declare function normalizePersian(text: string, { digits }?: NormalizeOptions): string;

package/dist/text.js

@@ -0,0 +1,23 @@
+import { toEnDigits, toFaDigits } from "./digits.js";
+/**
+ * یکدست‌سازی متن فارسی برای ذخیره و جستجو:
+ * «ي» و «ى» عربی ← «ی»، «ك» ← «ک»، «ة» ← «ه»، حذف اعراب و کشیده (ـ)،
+ * و جمع کردن فاصله‌ها و نیم‌فاصله‌های تکراری.
+ */
+export function normalizePersian(text, { digits } = {}) {
+    let out = text
+        .replace(/[يى]/g, "ی")
+        .replace(/ك/g, "ک")
+        .replace(/ة/g, "ه")
+        .replace(/[ً-ٰٟ]/g, "") // اعراب
+        .replace(/ـ/g, "") // کشیده
+        .replace(/‌{2,}/g, "‌")
+        .replace(/ *‌ */g, "‌")
+        .replace(/[ \t]{2,}/g, " ")
+        .trim();
+    if (digits === "fa")
+        out = toFaDigits(toEnDigits(out));
+    if (digits === "latin")
+        out = toEnDigits(out);
+    return out;
+}

package/dist/words.d.ts

@@ -0,0 +1,5 @@
+/**
+ * عدد به حروف فارسی: 1250000 → «یک میلیون و دویست و پنجاه هزار».
+ * برای اعداد صحیح تا ۹۹۹ تریلیون. «هزار» بدون «یک» خوانده می‌شود (۱۰۰۰ → هزار).
+ */
+export declare function numberToWords(value: number | bigint): string;

package/dist/words.js

@@ -0,0 +1,44 @@
+const ONES = ["", "یک", "دو", "سه", "چهار", "پنج", "شش", "هفت", "هشت", "نه"];
+const TEENS = ["ده", "یازده", "دوازده", "سیزده", "چهارده", "پانزده", "شانزده", "هفده", "هجده", "نوزده"];
+const TENS = ["", "", "بیست", "سی", "چهل", "پنجاه", "شصت", "هفتاد", "هشتاد", "نود"];
+const HUNDREDS = ["", "صد", "دویست", "سیصد", "چهارصد", "پانصد", "ششصد", "هفتصد", "هشتصد", "نهصد"];
+const SCALES = ["", "هزار", "میلیون", "میلیارد", "تریلیون"];
+function under1000(n) {
+    const parts = [];
+    const h = Math.floor(n / 100);
+    const rest = n % 100;
+    if (h)
+        parts.push(HUNDREDS[h]);
+    if (rest >= 10 && rest < 20)
+        parts.push(TEENS[rest - 10]);
+    else {
+        if (rest >= 20)
+            parts.push(TENS[Math.floor(rest / 10)]);
+        if (rest % 10)
+            parts.push(ONES[rest % 10]);
+    }
+    return parts.join(" و ");
+}
+/**
+ * عدد به حروف فارسی: 1250000 → «یک میلیون و دویست و پنجاه هزار».
+ * برای اعداد صحیح تا ۹۹۹ تریلیون. «هزار» بدون «یک» خوانده می‌شود (۱۰۰۰ → هزار).
+ */
+export function numberToWords(value) {
+    let n = typeof value === "bigint" ? value : BigInt(Math.trunc(value));
+    if (n === 0n)
+        return "صفر";
+    const negative = n < 0n;
+    if (negative)
+        n = -n;
+    if (n >= 10n ** 15n)
+        throw new RangeError("عدد بزرگ‌تر از حد پشتیبانی‌شده است");
+    const groups = [];
+    for (let i = 0; n > 0n; i++, n /= 1000n) {
+        const g = Number(n % 1000n);
+        if (!g)
+            continue;
+        const words = i === 1 && g === 1 ? "" : under1000(g);
+        groups.unshift([words, SCALES[i]].filter(Boolean).join(" "));
+    }
+    return (negative ? "منفی " : "") + groups.join(" و ");
+}

package/package.json

@@ -1,6 +1,26 @@
 {
   "name": "@kashi-ui/persian",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.4.0",
+  "description": "ابزارهای فارسی کاشی: تاریخ شمسی، اعتبارسنجی کد ملی و شماره کارت، ارقام فارسی",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": { "types": "./dist/index.d.ts", "default": "./dist/index.js" },
+    "./package.json": "./package.json"
+  },
+  "files": ["dist", "README.md"],
+  "sideEffects": false,
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "test": "node --test test/*.test.mjs"
+  },
+  "devDependencies": { "typescript": "^5.6.0" },
+  "publishConfig": { "access": "public" },
+  "keywords": ["persian", "farsi", "jalali", "shamsi", "national-id", "iran", "date"],
+  "repository": { "type": "git", "url": "git+https://github.com/Sepantapouya/Kashi.git", "directory": "packages/persian" },
+  "homepage": "https://kashi.sepantapouya.com",
+  "bugs": "https://github.com/Sepantapouya/Kashi/issues",
+  "author": "Sepanta Pouya (https://sepantapouya.com)",
+  "license": "MIT"
+}